Site Redirection

GateIn Portal includes a mechanism to redirect user to a different site within the portal based on the characteristics of their browser. This is especially useful for redirecting users to a mobile optimized site if you detect they are accessing the portal from a mobile device.

Redirections can be based on various criteria:

The user agent string of the browser accessing the site
Any properties which can be determined via javascript. This can include things like screen size, pixel density and if the device supports touch or not.

We also include options to map the nodes between one site and another when performing the redirect. This allows for greater control over what page within the site a user will end up on when a redirect is performed.

The following sections will briefly explain how to configure and setup the service using xml the configuration files.

For details on how to configure site redirects using the administration user interface, please see the User Guide: Manage Site Redirections

Redirects are only performed once for a user and stored in a cookie. The site redirect service will always use the value stored in the cookie regardless if the redirect service configuration has changed. This allows for users to specify their own preferences without being redirected to their non-preferred site when the redirection rules change. For costly browser based property detection, this also means that this check is only performed once for a user and not on each subsequent access.

Configuring Site Redirections in XML

All of the XML configuration options to add a redirectable, or alternative site is done in the portal.xml file for that particular site.

By default, the portal.xml configuration file is only read the first time the portal is ever started. If you wish to make changes after the portal has already been started, please see Data Import Strategy for how this can be accomplished.

Adding a Redirectable Site

To add the site mobile as an alternative to the classic site you would modify the portal.xml file for the 'classic' site to include the following:

Adding a Redirectable Site

<portal-redirects>
    <portal-redirect>
      <redirect-site>mobile</redirect-site> <!-- (1) -->
      <name>Mobile</name> <!-- (2) -->
      <enabled>true</enabled> <!-- (3) -->
    </portal-redirect>
</portal-redirects>

The name of the site to redirect to
The name given to the redirect
If the redirect should currently be enabled or not

Now when accessing the classic site you should notice a link at the bottom to the mobile site. If the user clicks this link, they will be redirected to that site and their preference for the alternative site will be stored. This means the next time the user tries to access the classic site they will automatically be redirected to the mobile site instead.

This only creates a redirection link between already existing sites. You will still need to create the sites manually.

The above steps only create a one way link. If the user also wants to make the classic site an alternative for the mobile site they will have to configure the portal.xml for the mobile site. It is highly recommended to also configure the redirect on the other site to allow the user to return to the original size as well as to set their preference to the original site.

Automatic Redirection

The previous example only dealt with adding an option for a redirect and required user intervention to specify which site they preferred. The site redirection service can be configured to redirect a user automatically from one site to another. This can be based on either the user agent string of the clients browser or through a device detection page which can gather any data which can be gathered through javascript.

Automatic Redirection Based on User Agent String

The clients browser normally sends a string which describes in part the type and version of the browser used. This is the browser's user agent string. We can preform automatic redirects based on the values contained within this string.

An example configuration which will preform a redirect if the user agent string contains the case-insensitive string "foo" or the case-sensitive string "Bar" and does not contain the case-sensitive string "baz":

Example Redirect Based on User Agent Strings

<portal-redirects>
    <portal-redirect>
      <redirect-site>test</redirect-site>
      <name>Test</name>
      <enabled>true</enabled>
      <conditions>
        <condition>
          <name>Test Condition</name> <!-- (1) -->
          <user-agent>
            <contains>(?i)foo</contains> <!-- (2) -->
            <contains>Bar</contains> <!-- (2) -->
            <does-not-contain>baz</does-not-contain> <!-- (3) -->
          </user-agent>
       </condition>
      </conditions>
    </portal-redirect>
  </portal-redirects>

The name of the redirect condition
A list of strings to check if they exist within the user agent
A string to make sure is not within the user agent string

The condition is considered to pass if any of the contains options is matched and if none of the does-not-contain options are matched.

The format of the strings is the Java Regex Pattern format. This allows for powerful pattern matching capabilities. Please see the java regex documentations for more details.

Automatic Redirection Based on Device Properties

In some rare cases, using user agent strings may not be enough. You may need to determine some characteristics retrieve from the user's browser itself. The way we can do this is to send the user to another page first, run some javascript to gather some information and return this to the redirection service. This allows for some more powerful detection and redirection, but at the cost of extra complexity and performance degradation.

It is strongly recommended to use user agent based detection whenever possible. Redirection based on device properties should be avoided if possible due to performance reasons.

The Device Detection Page

The jsp page which does the detection is located:

gatein.ear/portal.war/device/detection.jsp

By default this page only detects a couple of simple options like screen width and height. To add more options, this page can be modified and calls to the javascript method addParameter() will make new options and values available to the service.

A simple configuration to detect that the touch.enabled property specified in the detection.jsp file returned the value true.

Device Properties Based Redirection XML Configuration

Example Redirection Based on Device Properties

<portal-redirects>
    <portal-redirect>
      <redirect-site>test</redirect-site>
      <name>Test</name>
      <enabled>true</enabled>
      <conditions>
        <condition>
          <name>Test Condition</name>
          <user-agent>
            <contains>.*</contains> <!-- (1) -->
          </user-agent>
          <device-properties>
            <device-property>
              <property-name>touch.enabled</property-name> <!-- (2) -->
              <equals>true</equals> <!-- (3) -->
            </device-property>
          </device-properties>
        </condition>
      </conditions>
    </portal-redirect>
  </portal-redirects>

Java Regex Pattern that specifies that any user agent string will work
specifies the name of the property retrieved from the detection page to check against
specifies the condition to check this property. The options include: equals, greater-than, less-than, and matches (which uses Java Pattern Regex format).

Multiple options can be used against a single device property. They must all match to satisfy the condition. This allows for detecting a value within a range by using both greater-than and less-than options.

Multople Property Options

<condition>
  <name>Test Condition</name>
  <user-agent>
    <contains>.*</contains>
  </user-agent>
  <device-properties>
    <device-property>
      <property-name>screen.width</property-name>
      <greater-than>320</greater-than>
      <less-than>1024</less-than>
    </device-property>
  </device-properties>
</condition>

If multiple <device-property> options are used, then they must all match to satisfy the condition.

As shown here, user agent string and device property detection can be used together. In this case it is specified to match any user agent string, but it could just have easily been configured to restrict based on the user agent string. The service will only ever redirect the user to the device detection page if the user agent string values passes. Narrowing the user agent string is strong advised to prevent unnecessary redirects to the device detection page.

Multiple Redirect Conditions

Multiple redirect conditions can be specified. The conditions are checked sequentially and perform the redirect when it encounters a condition which passes.

For example, the following will perform the redirect if the user agent string contains the string "foo". If the user agent string does not contain "foo" it will check if it contains "bar" and the browser detection pare returns a touch.enabled property of true. If neither of these conditions pass, the redirect will not happen and the user's preference will be set to the original site.

Multiple Redirect Conditions Example

<conditions>
  <condition>
    <name>Check Foo</name>
    <user-agent>
      <contains>foo</contains>
    </user-agent>
  </condition>
  <condition>
    <name>Check Touch</name>
    <user-agent>
      <contains>bar</contains>
    </user-agent>
    <device-properties>
      <device-property>
        <property-name>touch.enabled</property-name>
        <equals>true</equals>
      </device-property>
    </device-properties>
  </condition>
</conditions>

Mapping Page Nodes In Redirects

When redirecting between sites, what you are really doing is redirecting the user from one page node on one site to a node on another side. There are a few configuration options on how to handle node redirects.

Explicit Node Mappings

The admin can configure explicit node mappings between the original site and the redirect site. For example, for a redirect between classic and mobile sites, it can be configure that http://localhost:8080/portal/classic/home/pageA would get redirected to http://localhost:8080/portal/mobile/pageB

If node mappings exists, they are always looked at first when preforming a redirect.

Node Name Matching

If the node is not specified in the node mappings, then the redirect can be configured to try and match the nodes from the original site to a node of the same path on the redirect site.

This means if the a redirect is configured between the classic and mobile sites and the user tries to access http://localhost:8080/portal/classic/home/pageXYZ and it the node /home/pageXYZ exists on the mobile site, they will be redirected to http://localhost:8080/portal/classic/home/pageXYZ if the node /home/pageXYZ does not exist on the redirect site, then the service will look to the unresolved node setting to determine where the redirect should go.

Node name mapping is enabled by default, but can be disable if required.

Resolving Unresolved Nodes

If the node is not listed in the node mappings, and the node name mappings could not resolve the node, then the node is considered currently unresolved. Using <unresolved-nodes> XML element, the service can be configured to handle these unresolved nodes in couple of different ways:

REDIRECT – Redirect Anyway

If the node is not resolved, perform the redirect and use the node path from the original site. For example, if a redirect is to occur between classic and mobile and the user accesses http://localhost:8080/portal/classic/home/pageABC but pageABC does not exist on the redirect site, the user will still be redirected to http://localhost:8080/portal/mobile/home/pageABC. This will use the portal's node resolving configuration, which by default will resolve to the next available node in the path.

NO_REDIRECT – Abort the Redirect

With this option, if the node does not exist on the redirect site, the redirect will not take place and the user will continue on to the original uri.

ROOT – Redirect to the Sites Root

WIth this option, if the node does not exist on the redirect site, the user will be redirected to the root of the redirect site. For example, with a redirect between classic and mobile if the node /home/PageA/PageB does not exist on the redirect site, the user will be redirected to http://localhost:8080/portal/mobile even if /home/PageA exists on the mobile site.

COMMON_ANCESTOR_NAME_MATCH – Redirect Based on a Common Ancestor Node

This option is similar to the redirect anyways options and behaves the same way if the portal is using the default node resolver.
For example, if the node on the original site is /home/PageA/PageB this option will first check if /home/PageA/PageB exists on the redirect site, then /home/PageA, then /home and will finally resolve to the root of the redirect site if no match can be found.

Node Mapping XML Example

The following is an example on how to setup node mappings.

Node Mapping XML Example

<portal-redirect>
  <redirect-site>mobile</redirect-site>
  <name>Mobile</name>
  <enabled>true</enabled>
  <conditions>
    ...
  </conditions>
  <node-mapping>
    <node-map> <!-- (1) -->
      <origin-node>home</origin-node>
      <redirect-node>mobileHome</redirect-node>
    </node-map>
    <node-map> <!-- (2) -->
      <origin-node>foo</origin-node>
      <redirect-node>bar</redirect-node>
    </node-map>
    <use-node-name-mapping>true</user-node-name-mapping> <!-- (3) -->
    <unresolved-nodes>NO_REDIRECT</unresolved-nodes> <!-- (4) -->
  <node-mapping>
</portal-redirect>

/home on the original site will always be resolved to /mobileHome on the redirect site
/foo on the original site will always be resolved to /bar on the redirect site
node name matching will be attempted
if the origin node is not resolved from either the mapping or the name matching, then no redirect is to occur.